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Learn to properly use ConvertTo-HTML to produce multi-section, well-formed HTML 
reports — but then go further with a custom EnhancedHTML module! Produce beautiful, 
color-coded, dynamic, multi-section reports easily and quickly. By Don Jones. 


Visit Penflip.com/powershellorg to check for newer editions of this ebook. 


This guide is released under the Creative Commons Attribution-NoDerivs 3.0 Unported 
License. The authors encourage you to redistribute this file as widely as possible, but ask 
that you do not modify the document. 


PowerShell.org ebooks are works-in-progress, and many are curated by members of the 
community. We encourage you to check back for new editions at least twice a year, by 
visiting Penflip.com/powershellorg. 


Downloading this book: You can download this book ina number of different formats 
(including Epub, Pdf, Microsoft Word and Plain Text) by clicking on the ‘Download’ link on 
the right. Note that PDF has problems - see below. 


PDF Users: Penflip’s PDF export often doesn’t include the entire ebook content. We’ve 
reported this problem to them; in the meantime, please consider using a different format, 
such as EPUB, when you're downloading the book. 


* Contributing*: You may register to make corrections, contributions, and other changes to 
the text - we welcome your contributions! check out our contributor tips and notes before 
jumping in. 

Getting the Code The code related to this book can be found in the 


https://www.powershellgallery.com/packages/EnhancedHTML2/ . That page includes 


download instructions. Code can also be found at 


https://onedrive.live.com/redir?resid=7f868aa697b937fe%21107 . 
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2. HTML Report Basics 


First, understand that PowerShell isn’t limited to creating reports in HTML. But I like HTML 
because it’s flexible, can be easily e-mailed, and can be more easily made to look pretty than 
a plain-text report. But before you dive in, you do need to know a bit about how HTML 
works. 


An HTML page is just a plain text file, looking something like this: 


<10 YPE tml PUBLIC 
a ne="httt wwv.w rEe/ivyy html"> 
head> 

le>HTML TABLE</titie> 


/head>< iy> 
: > 

lg ><colf/><col/><col/><col/>< {></ igroup> 
tr><th>ComputerName</th><th>Drive</th><th>Free (GB) </th><th>Free(%)</th><th>Size (GB)</th></tr> 
tr><td>CLIENT</td><td>C:</rd><td>49</td><trd>82</td><td>60</td></tr> 

/table> 
/t 


: iy></html> 

When read by a browser, this file is rendered into the display you see within the browser's 
window. The same applies to e-mail clients capable of displaying HTML content. While you, 
as a person, can obviously put anything you want into the file, if you want the output to 
look right you need to follow the rules that browsers expect. 


One of those rules is that each file should contain one, and only one, HTML document. 
That’s all of the content between the <HTML> tag and the </HTML> tag (tag names aren't 
case-sensitive, and it’s common to see them in all-lowercase as in the example above). | 
mention this because one of the most common things I'll see folks do in PowerShell looks 
something like this: 


Get-WmiObject -class Win32_OperatingSystem | ConvertTo-HTML | Out-File 
report.html Get-WmiObject -class Win32_BIOS | ConvertTo-HTML | Out-File 


report.html -append Get-WmiObject -class Win32_Service | ConvertTo-HTML | 
Out-File report.html -append 


“Aaartrggh,” says my colon every time I see that. You're basically telling PowerShell to 
create three complete HTML documents and jam them into a single file. While some 
browsers (Internet Explorer, notable) will figure that out and display something, it’s just 
wrong. Once you start getting fancy with reports, you'll figure out pretty quickly that this 
approach is painful. It isn’t PowerShell’s fault; you're just not following the rules. Hence this 
guide! 


You'll notice that the HTML consists of a lot of other tags, too: <TABLE>, <TD>, <HEAD>, and 
so on. Most of these are paired, meaning they come in an opening tag like <TD> anda closing 
tag like </TD>. The <TD> tag represents a table cell, and everything between those tags is 
considered the contents of that cell. 


The <HEAD> section is important. What’s inside there isn’t normally visible in the browser; 
instead, the browser focuses on what's in the <BODY> section. The <HEAD> section provides 
additional meta-data, like what the title of the page will be (as displayed in the browser’s 


window title bar or tab, not in the page itself), any style sheets or scripts that are attached 
to the page, and so on. We're going to do some pretty awesome stuff with the <HEAD> 
section, trust me. 


You'll also notice that this HTML is pretty “clean,” as opposed to, say, the HTML output by 
Microsoft Word. This HTML doesn’t have a lot of visual information embedded in it, like 
colors or fonts. That’s good, because it follows correct HTML practices of separating 
formatting information from the document structure. It’s disappointing at first, because 
your HTML pages look really, really boring. But we’re going to fix that, also. 


In order to help the narrative in this book stay focused, I’m going to start with a single 
example. In that example, we're going to retrieve multiple bits of information about a 
remote computer, and format it all into a pretty, dynamic HTML report. Hopefully, you'll be 
able to focus on the techniques I’m showing you, and adapt those to your own specific 
needs. 


In my example, I want the report to have five sections, each with the following information: 
e¢ Computer Information 
e The computer’s operating system version, build number, and service pack version. 


e Hardware info: the amount of installed RAM and number of processes, along with 
the manufacturer and model. 


e An list of all processes running on the machine. 
e A list of all services which are set to start automatically, but which aren’t running. 


e Information about all physical network adapters in the computer. Not IP addresses, 
necessarily - hardware information like MAC address. 


I realize this isn’t a universally-interesting set of information, but these sections will allow 
be to demonstrate some specific techniques. Again, I’m hoping that you can adapt these to 
your precise needs. 


File is missing 


3. Gathering the Information 


I’m a big fan of modular programming. Big, big fan. With that in mind, I tend to write 
functions that gather the information I want to be in my report - and I'll usually do one 
function per major section of my report. You'll see ina bit how that’s beneficial. By writing 
each function individually, I make it easier to use that same information in other tasks, and 
I make it easier to debug each one. The trick is to have each function output a single type of 
object that combines all of the information for that report section. I’ve created five 
functions, which I’ve pasted into a single script file. I’ll give you each of those functions one 
at a time, with a brief commentary for each. Here’s the first: 


function Get-InfoOS { [CmdletBinding() ] param( 
[Parameter (Mandatory=$True) |] [string] $ComputerName ) gos = Get- 
WmiObject -class Win32_OperatingSystem -ComputerName $ComputerName $props 


= @{'OSVersion'=$os.version; 

"SPVersion'=$os.servicepackmajorversion; 

"OSBuild'=$o0s.buildnumber} New-Object -TypeName PSObject -Property $props 
} 


This is a straightforward function, and the main reason I bothered to even make it a 
function - as opposed to just using Get-WmiObject directly - is that I want different 
property names, like “OSVersion” instead of just “Version.” That said, I tend to follow this 
exact same programming pattern for all info-retrieval functions, just to keep them 
consistent. 


function Get-InfoCompSystem { [CmdletBinding() ] param( 

[Parameter (Mandatory=$True) ][string ] $ComputerName ) $cs = Get- 
WmiObject -class Win32_ComputerSystem -ComputerName $ComputerName $props 
= @{'Model'=$cs.model; "Manufacturer '=$cs.manufacturer; 


"RAM (GB)'="{O:N2}" -f ($cs.totalphysicalmemory / 1GB); 

"Sockets '=$cs.numberof processors; 

"Cores '=$cs.numberoflogicalprocessors} New-Object -TypeName PSObject - 
Property $props } 


Very similar to the last one. You'll notice here that I’m using the -f formatting operator with 
the RAM property, so that I get a value in gigabytes with 2 decimal places. The native value 
is in bytes, which isn’t useful for me. 


function Get-InfoBadService { [CmdletBinding() ] param( 

[Parameter (Mandatory=$True) ][string ] $ComputerName ) $svcs = Get- 
WmiObject -class Win32_Service -ComputerName $ComputerName ~ - 
Filter "StartMode='Auto' AND State<>'Running'" foreach ($svc in $svcs) { 


$props = @{'ServiceName'=$svc.name; 

"LogonAccount '=$svc.startname; 

"DisplayName '=$svc.displayname} New-Object -TypeName PSObject - 
Property $props } } 


Here, I’ve had to recognize that I'll be getting back more than one object from WMI, so I 
have to enumerate through them using a ForEach construct. Again, I’m primarily just 
renaming properties. I absolutely could have done that with a Select-Object command, but I 


like to keep the overall function structure similar to my other functions. Just a personal 
preference that helps me include fewer bugs, since I’m used to doing things this way. 


function Get-InfoProc { 

[CmdletBinding()] 

Param( 
[Parameter(Mandatory=$True)]|[string]$ComputerName 
) $procs = Get-WmiObject -class Win32_Process -ComputerName $ComputerName 
foreach ($proc in $procs) { 

$props = @{‘ProcName’=$proc.name; 
‘Executable’=$proc.ExecutablePath} 

New-Object -TypeName PSObject -Property $props 

} 

} 


Very similar to the function for services. You can probably start to see how using 
this same structure makes a certain amount of copy-and-paste pretty effective 
when I create a new function. 


function Get-InfoNIC { 

[CmdletBinding()] 

param( 

[Parameter(Mandatory=$True) |[string]$ComputerName 
) 

$nics = Get-WmiObject -class Win32_NetworkAdapter -ComputerName $ComputerName ‘ 
-Filter “PhysicalAdapter=True” 

foreach ($nic in $nics) { 

$props = @{‘NICName’=$nic.servicename; 
‘Speed’=$nic.speed / 1MB -as [int]; 
‘Manufacturer’=$nic.manufacturer; 
‘MACAddress’=$nic.macaddress} 

New-Object -TypeName PSObject -Property $props 

i 

i 


The main thing of note here is how I've converted the speed property, which is 


matively in bytes, to megabytes. Because I don't care about decimal places here 
(I want a whole number), casting the value as an integer, by using the -as 
operator, is easier for me than the -f formatting operator. Also, it gives me a 
chance to show you this technique! 


Note that, for the purposes of this book, I'm going to be putting these functions 


into the same script file as the rest of my code, which actually generates the 
HTML. I don't normally do that. Normally, info-retrieval functions go into a 
script module, and I then write my HTML-generation script to load that module. 
Having the functions in a module makes them easier to use elsewhere, if I want 
to. I'm skipping the module this time just to keep things simpler for this 
demonstration. If you want to learn more about script modules, pick up Learn 
PowerShell Toolmaking in a Month of Lunches or PowerShell in Depth, both of 
which are available from Manning.com, 


# Building the HTML 


I'm going to abandon the native ConvertTo-HTML cmdlet that I've discussed so far, 


Instead, I'm going to ask you to use the EnhancedHTML2 module that comes with 
this ebook. Note that, as of October 2013, this is a new version of the module 
- it's simpler than the EnhancedHTML module I introduced with the original 


edition of this book. 


Let's start with the script that actually uses the module. It's included with this 


book as EnhancedHTML2-Demo.psi, so herein I'm going to paste the whole thing, 
and then insert explanations about what each bit does. Note that, if you're 
reading this in something other than PDF, I can't control how the code will 
line-wrap, so it might look wacky. 


